package com.sp.fresh_produce.service;

import com.sp.fresh_produce.model.pojo.User;

/**
 * 用户领域服务接口
 * <p>
 * 定义用户相关的核心领域能力，包括查询、注册、认证、口令匹配与更新个性签名等。
 * 具体实现见 {@code com.sp.fresh_produce.service.impl} 包。
 */
public interface UserService {
    /**
     * 按主键查询用户
     *
     * @param id 用户 ID
     * @return 用户实体，可能为 null
     */
    User getUserById(Integer id);

    /**
     * 注册新用户（不做重名校验）
     *
     * @param username 用户名
     * @param password 明文密码，将在实现中加密存储
     * @return 受影响的行数
     */
    int register(String username, String password);

    /**
     * 按用户名查询用户
     *
     * @param username 用户名
     * @return 用户实体，可能为 null
     */
    User getUserByUsername(String username);

    /**
     * 匹配密码
     *
     * @param rawPassword     明文密码
     * @param encodedPassword 加密后的密码
     * @return 是否匹配
     */
    boolean matchesPassword(String rawPassword, String encodedPassword);

    /**
     * 用户认证
     * <p>
     * 使用用户名与密码进行认证；当 {@code adminRequired} 为 true 时，还将校验用户是否为管理员。
     * 成功时返回用户实体，并将密码字段置为 null。
     *
     * @param username      用户名
     * @param password      明文密码
     * @param adminRequired 是否要求管理员权限
     * @return 认证通过的用户对象（密码已置空）
     */
    User authenticate(String username, String password, boolean adminRequired);

    /**
     * 注册新用户（带重名校验）
     * <p>
     * 当用户名已存在时抛出业务异常。
     *
     * @param username 用户名
     * @param password 明文密码
     * @return 插入的行数
     */
    int registerOrThrow(String username, String password);

    /**
     * 更新当前用户的个性签名
     * <p>
     * 需要登录用户自身的 ID，方法实现应保证幂等。
     *
     * @param operatorUserId 当前登录用户 ID
     * @param newSignature   新的个性签名（实现中会做去空格归一化）
     * @return 受影响的行数
     */
    int updatePersonalizedSignature(Integer operatorUserId, String newSignature);
}
